Setting Properties on Effects and Transitions

Many effects and transitions support properties that control their appearance. For example, the Volume Envelope effect has a property that specifies the volume level. Using the IPropertySetter interface, an application can set the value of a property across a range of times.

To set a property, perform the following steps.

1. Create an instance of the property setter (CLSID_PropertySetter).
2. Fill DEXTER_PARAM and DEXTER_VALUE structures with the property data. These structures are discussed below.
3. Pass the DEXTER_PARAM and DEXTER_VALUE structures to the IPropertySetter::AddProp method.
4. Repeat steps 2 and 3 for each property you want to set.
5. Pass the IPropertySetter interface pointer to the IAMTimelineObj::SetPropertySetter method.

The DEXTER_PARAM structure specifies which property is being set. It contains the following members.

• Name: Name of the property
• dispID: Reserved, must be zero
• nValues: Number of values

The DEXTER_VALUE structure specifies the value of a property at a given time. It contains the following members.

• v: VARIANT type that specifies a new value for the property. The vt member of this VARIANT defines the data type of the property. For more information on the VARIANT type, see the Platform SDK.
• rt: Reference time when the property assumes this value, relative to the starting time of the effect or transition. The start time of the effect or transition is relative to the start time of its parent object.
• dwInterp: Flag that specifies how the property changes from the previous value to the new value. With the DEXTERF_JUMP flag, the property jumps instantly to the new value at the specified time. With the DEXTERF_INTERPOLATE flag, the property is interpolated linearly from the previous value.

If you set the vt member to VT_BSTR, the property setter makes any necessary conversions. For floating-point values, include the leading zero before the decimal place. For example, 0.3, not .3.

The value of a property can change over time, so the IPropertySetter::AddProp method takes a single DEXTER_PARAM structure and a pointer to an array of DEXTER_VALUE structures. The array defines a set of time-based values for the property. The members of the array must be in ascending time order, and the nValues member of the DEXTER_PARAM structure must equal the length of the array.

The following code example creates property data for the SMPTE Wipe transition. It sets the wipe code to 120, which creates an oval wipe. It sets the reference time to zero, indicating the start of the transition.

IPropertySetter     *pProp;   // Property setter
IAMTimelineObj      *pTransObj;  // Transition object
// Create an SMPTE Wipe transition object. (Not shown)

CoCreateInstance(CLSID_PropertySetter, 
    NULL, CLSCTX_INPROC_SERVER, 
    IID_IPropertySetter, (void**) &pProp);

DEXTER_PARAM param;
DEXTER_VALUE *pValue = (DEXTER_VALUE *)CoTaskMemAlloc(sizeof(DEXTER_VALUE));

// Initialize the parameter. 
param.Name = SysAllocString(L"MaskNum");
param.dispID = 0;
param.nValues = 1;

// Initialize the value.
pValue->v.vt = VT_BSTR;
pValue->v.bstrVal = SysAllocString(L"120"); // Oval
pValue->rt = 0;
pValue->dwInterp = DEXTERF_JUMP;

pProp->AddProp(param, pValue);

// Free allocated resources.
SysFreeString(param.Name);
VariantClear(&(pValue->v));
CoTaskMemFree(pValue);

// Set the property on the transition.
pTransObj->SetPropertySetter(pProp);
pProp->Release();